short-uuid

What is short-uuid?

The short-uuid npm package is a utility for generating and working with short, URL-friendly UUIDs. It provides a way to encode and decode UUIDs into shorter formats, making them more suitable for use in URLs, database keys, and other contexts where a shorter identifier is beneficial.

What are short-uuid's main functionalities?

Generate Short UUID

This feature allows you to generate a new short UUID. The `short()` function creates a new translator instance, and `translator.new()` generates a new short UUID.

const short = require('short-uuid');
const translator = short();
const shortUUID = translator.new();
console.log(shortUUID);

Translate UUID to Short UUID

This feature allows you to convert a standard UUID to a short UUID. The `translator.fromUUID(uuid)` method takes a standard UUID and returns its shorter version.

const short = require('short-uuid');
const translator = short();
const uuid = '123e4567-e89b-12d3-a456-426614174000';
const shortUUID = translator.fromUUID(uuid);
console.log(shortUUID);

Translate Short UUID to UUID

This feature allows you to convert a short UUID back to a standard UUID. The `translator.toUUID(shortUUID)` method takes a short UUID and returns the original standard UUID.

const short = require('short-uuid');
const translator = short();
const shortUUID = 'SOME_SHORT_UUID';
const uuid = translator.toUUID(shortUUID);
console.log(uuid);

Custom Alphabet

This feature allows you to create a translator with a custom alphabet. The `short('0123456789abcdef')` function creates a new translator instance that uses the specified alphabet for encoding.

const short = require('short-uuid');
const customTranslator = short('0123456789abcdef');
const shortUUID = customTranslator.new();
console.log(shortUUID);

Other packages similar to short-uuid

uuid

The uuid package is a popular library for generating RFC4122 UUIDs. Unlike short-uuid, it does not provide functionality for shortening UUIDs, but it is widely used for generating standard UUIDs in various versions (v1, v3, v4, v5).

nanoid

Nanoid is a small, secure, URL-friendly unique string ID generator. It is similar to short-uuid in that it generates shorter IDs suitable for URLs, but it does not focus on translating standard UUIDs to shorter formats and vice versa.

cuid

Cuid is a collision-resistant ID generator optimized for horizontal scaling and performance. It generates short, readable IDs that are URL-friendly, similar to short-uuid, but it does not provide translation between standard UUIDs and short UUIDs.

README

short-uuid

Generate and translate standard UUIDs into shorter - or just different - formats and back.

v4.2.2

Major Changes in 4.0.0

• 🛑 short-uuid will now throw an error when provided an alphabet with duplicate characters. Duplicate characters will cause translation errors.
• ℹ️ 4.0.0 is written in modern ECMAScript. It uses features through ES9/ES2018.
• ℹ️ By default, short-uuid will pad shortened IDs to a consistent length.
  • Padding does not affect translation, and the values are compatible with previous releases.
  • Padding can be disabled with the option consistentLength: false when instantiating a translator. This is consistent with previous versions.
• ℹ️ 4.x does not include a pre-built version for browsers. If needed, 3.1.1 is compatible, but does not pad to a consistent length.

Quick Start

const short = require('short-uuid');

// Quick start with flickrBase58 format
short.generate(); // 73WakrfVbNJBaAmhQtEeDv

Details

short-uuid starts with RFC4122 v4-compliant UUIDs and translates them into other, usually shorter formats. It also provides translators to convert back and forth from RFC compliant UUIDs to the shorter formats.

As of 4.0.0, formats return consistent-length values unless specifically requested. This is done by padding the start with the first ([0]) character in the alphabet. Previous versions can translate padded formats back to UUID.

const short = require('short-uuid');

const translator = short(); // Defaults to flickrBase58
const decimalTranslator = short("0123456789"); // Provide a specific alphabet for translation
const cookieTranslator = short(short.constants.cookieBase90); // Use a constant for translation

// Generate a shortened v4 UUID
translator.new(); // mhvXdrZT4jP5T8vBxuvm75
translator.generate(); // An alias for new.

// Translate UUIDs to and from the shortened format
translator.toUUID(shortId); // a44521d0-0fb8-4ade-8002-3385545c3318
translator.fromUUID(regularUUID); // mhvXdrZT4jP5T8vBxuvm75

// Generate plain UUIDs
// - From the library without creating a translator
short.uuid(); // fd5c084c-ff7c-4651-9a52-37096242d81c
// - Each translator provides the uuid.v4() function, too
translator.uuid(); // 3023b0f5-ec55-4e75-9cd8-104700698052

// See the alphabet used by a translator
translator.alphabet;

// The maximum length a translated uuid will be with its alphabet.
translator.maxLength;

// View the constants
short.constants.flickrBase58; // Avoids similar characters (0/O, 1/I/l, etc.)
short.constants.cookieBase90; // Safe for HTTP cookies values for smaller IDs.

Options

short-uuid 4.0.0 adds support for options when creating a translator. This will support additional configuration in the future.

const short = require('short-uuid');

// By default shortened values are now padded for consistent length.
// If you want to produce variable lengths, like in 3.1.1
const translator = short(short.constants.flickrBase58, {
  consistentLength: false,
});

// Generate a shortened v4 UUID
translator.new(); // mhvXdrZT4jP5T8vBxuvm75

• consistentLength - Controls padding on shortened values. Default is true.

Support

short-uuid 4.0.0 and later is confirmed to work on Node 8.x and later.

• Pre-compiled browser version is planned for future release.

short-uuid 3.1.1 and lower is confirmed to work on Node 0.10.x and later, and browsers with a precompiled library proposed by voronianski.

Notes

short-uuid provides RFC4122 v4-compliant UUIDs, thanks to uuid.

TypeScript definitions are included, thanks to alexturek.

Recent Release Notes

4.1.0 adds a maxLength value to translators for reference 4.0.3 fixes default generate 4.0.1 adds consistent length translation and throws an error if provided an invalid alphabet. 3.1.1 updated dev dependencies which required dropping Node 4.x build test. Last Browserify distribution version temporarily. 2.3.4 corrects the behavior for UUIDs with uppercase letters. Last version to build on Node 0.x.

Please see Revisions for information on previous versions.

Changelog

[4.2.2] - 2022-10-18

Changed

• Updated README